<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Getting Started &mdash; cpp-netlib v0.12.0</title>
    
    <link rel="stylesheet" href="_static/pyramid.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '0.12.0',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="top" title="cpp-netlib v0.12.0" href="contents.html" />
    <link rel="next" title="Examples" href="examples.html" />
    <link rel="prev" title="What’s New" href="whats_new.html" />
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Neuton&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
<link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Nobile:regular,italic,bold,bolditalic&amp;subset=latin" type="text/css" media="screen" charset="utf-8" />
<!--[if lte IE 6]>
<link rel="stylesheet" href="_static/ie6.css" type="text/css" media="screen" charset="utf-8" />
<![endif]-->

  </head>
  <body role="document">

    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="examples.html" title="Examples"
             accesskey="N">next</a></li>
        <li class="right" >
          <a href="whats_new.html" title="What’s New"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="contents.html">cpp-netlib v0.12.0</a> &raquo;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="getting-started">
<span id="id1"></span><h1>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h1>
<div class="section" id="downloading-an-official-release">
<h2>Downloading an official release<a class="headerlink" href="#downloading-an-official-release" title="Permalink to this headline">¶</a></h2>
<p>You can find links to the latest official release from the project&#8217;s official
website:</p>
<blockquote>
<div><a class="reference external" href="http://cpp-netlib.org/">http://cpp-netlib.org/</a></div></blockquote>
<p>All previous stable versions of <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> can be downloaded from
<a class="reference external" href="http://github.com/cpp-netlib/cpp-netlib/downloads">Github</a> from this url:</p>
<blockquote>
<div><a class="reference external" href="http://github.com/cpp-netlib/cpp-netlib/downloads">http://github.com/cpp-netlib/cpp-netlib/downloads</a></div></blockquote>
<p>Each release is available as gzipped (Using the command
<code class="docutils literal"><span class="pre">tar</span> <span class="pre">xzf</span> <span class="pre">cpp-netlib.tar.gz</span></code>) or bzipped (Using <code class="docutils literal"><span class="pre">tar</span> <span class="pre">xjf</span>
<span class="pre">cpp-netlib.tar.bz2</span></code>) tarball, or as a zipfile (<code class="docutils literal"><span class="pre">unzip</span>
<span class="pre">cpp-netlib.zip</span></code>, or on Windows using a tool such as <a class="reference external" href="http://www.7-zip.org/">7zip</a>).</p>
</div>
<div class="section" id="downloading-a-development-version">
<h2>Downloading a development version<a class="headerlink" href="#downloading-a-development-version" title="Permalink to this headline">¶</a></h2>
<p>The <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> uses <a class="reference external" href="http://git-scm.com/">Git</a> for source control, so to use any
development versions Git must be installed on your system.</p>
<p>Using the command line, the command to get the latest code is:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>shell$ git clone git://github.com/cpp-netlib/cpp-netlib.git
</pre></div>
</div>
<p>This should be enough information get to started.  To do more complex
things with Git, such as pulling changes or checking out a new branch,
refer to the <a class="reference external" href="http://git-scm.com/documentation">Git documentation</a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Previous versions of <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> referred to the
<em>mikhailberis</em> repository as the main development repository. This
account is still valid, but not always up-to-date. In the interest of
consistency, the main repository has been changed to <em>cpp-netlib</em>.</p>
</div>
<p>Windows users need to use <a class="reference external" href="http://code.google.com/p/msysgit/downloads/list">msysGit</a>, and to invoke the command above
from a shell.</p>
<p>For fans of <a class="reference external" href="http://subversion.tigris.org/">Subversion</a>, the same code can be checked out from
<a class="reference external" href="http://svn.github.com/cpp-netlib/cpp-netlib.git">http://svn.github.com/cpp-netlib/cpp-netlib.git</a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> project is hosted on <a class="reference external" href="http://github.com/cpp-netlib/cpp-netlib/downloads">GitHub</a> and follows the
prescribed development model for <a class="reference external" href="http://github.com/cpp-netlib/cpp-netlib/downloads">GitHub</a> based projects. This means in case
you want to submit patches, you will have to create a fork of the project
(read up on <a class="reference external" href="http://help.github.com/forking/">forking</a>) and then submit a pull request (read up on submitting
<a class="reference external" href="http://help.github.com/pull-requests/">pull requests</a>).</p>
</div>
</div>
<div class="section" id="getting-boost">
<h2>Getting Boost<a class="headerlink" href="#getting-boost" title="Permalink to this headline">¶</a></h2>
<p><code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> depends on <a class="reference external" href="http://www.boost.org/doc/libs/release/more/getting_started/index.html">Boost</a>.  It should work for any version
of Boost above 1.50.0.  If Boost is not installed on your system, the
latest package can be found on the <a class="reference external" href="http://www.boost.org/users/download/">Boost web-site</a>.  The environment
variable <code class="docutils literal"><span class="pre">BOOST_ROOT</span></code> must be defined, which must be the full path
name of the top directory of the Boost distribution.  Although Boost
is mostly header only, applications built using <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code>
still requires linking with <a class="reference external" href="http://www.boost.org/libs/system/index.html">Boost.System</a>, <a class="reference external" href="http://www.boost.org/libs/date_time/index.html">Boost.Date_time</a>, and
<a class="reference external" href="http://www.boost.org/libs/regex/index.html">Boost.Regex</a>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You can follow the steps in the <a class="reference external" href="http://www.boost.org/doc/libs/release/more/getting_started/index.html">Boost Getting Started</a> guide to
install Boost into your development system.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">There is a known incompatibility between <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> and
Boost 1.46.1 on some compilers. It is not recommended to use <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code>
with Boost 1.46.1. Some have reported though that Boost 1.47.0
and <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> work together better.</p>
</div>
</div>
<div class="section" id="getting-cmake">
<h2>Getting CMake<a class="headerlink" href="#getting-cmake" title="Permalink to this headline">¶</a></h2>
<p>The <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> uses <a class="reference external" href="http://www.cmake.org/">CMake</a> to generate platform-specific build files. If
you intend to run the test suite, you can follow the instructions below.
Otherwise, you don&#8217;t need CMake to use <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> in your project. The
<code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> requires CMake version 2.8 or higher.</p>
<p>Let&#8217;s assume that you have unpacked the <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> at the top of your
HOME directory. On Unix-like systems you will typically be able to change into
your HOME directory using the command <code class="docutils literal"><span class="pre">cd</span> <span class="pre">~</span></code>. This sample below assumes that
the <code class="docutils literal"><span class="pre">~/cpp-netlib</span></code> directory exists, and is the top-level directory of the
<code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> release.</p>
</div>
<div class="section" id="building-with-cmake">
<h2>Building with CMake<a class="headerlink" href="#building-with-cmake" title="Permalink to this headline">¶</a></h2>
<p>To build the tests that come with <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code>, we first need to configure the
build system to use our compiler of choice. This is done by running the
<code class="docutils literal"><span class="pre">cmake</span></code> command at the top-level directory of <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> with
additional parameters:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ mkdir ~/cpp-netlib-build
$ cd ~/cpp-netlib-build
$ cmake -DCMAKE_BUILD_TYPE=Debug \
&gt;       -DCMAKE_C_COMPILER=gcc   \
&gt;       -DCMAKE_CXX_COMPILER=g++ \
&gt;       ../cpp-netlib
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">While it&#8217;s not compulsory, it&#8217;s recommended that
<code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> is built outside the source directory.
For the purposes of documentation, we&#8217;ll assume that all
builds are done in <code class="docutils literal"><span class="pre">~/cpp-netlib-build</span></code>.</p>
</div>
<p>If you intend to use the SSL support when using the HTTP client libraries in
<code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code>, you may need to build it with <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> installed or at least
available to CMake. If you have the development headers for <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> installed
on your system when you build <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code>, CMake will be able to detect it
and set the <code class="docutils literal"><span class="pre">BOOST_NETWORK_ENABLE_HTTPS</span></code> macro when building the library to
support HTTPS URIs.</p>
<p>One example for building the library with <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> support with a custom
(non-installed) version of <a class="reference external" href="http://www.openssl.org/">OpenSSL</a> is by doing the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ cmake -DCMAKE_BUILD_TYPE=Debug \
&gt;       -DCMAKE_C_COMPILER=clang \
&gt;       -DCMAKE_CXX_COMPILER=clang++ \
&gt;       -DOPENSSL_ROOT_DIR=/Users/dberris/homebrew/Cellar/openssl/1.0.1f
&gt;       ../cpp-netlib
</pre></div>
</div>
<p>You can also use a different root directory for the <a class="reference external" href="http://www.boost.org/doc/libs/release/more/getting_started/index.html">Boost</a> project by using the
<code class="docutils literal"><span class="pre">-DBOOST_ROOT</span></code> configuration option to CMake. This is useful if you intend to
build the library with a specific version of Boost that you&#8217;ve built in a
separate directory:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ cmake -DCMAKE_BUILD_TYPE=Debug \
&gt;       -DCMAKE_C_COMPILER=clang \
&gt;       -DCMAKE_CXX_COMPILER=clang++ \
&gt;       -DOPENSSL_ROOT_DIR=/Users/dberris/homebrew/Cellar/openssl/1.0.1f \
&gt;       -DBOOST_ROOT=/Users/dberris/Source/boost_1_55_0
&gt;       ../cpp-netlib
</pre></div>
</div>
<div class="section" id="building-on-linux">
<h3>Building on Linux<a class="headerlink" href="#building-on-linux" title="Permalink to this headline">¶</a></h3>
<p>On Linux, this will generate the appropriate Makefiles that will enable you to
build and run the tests and examples that come with <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code>. To build
the tests, you can run <code class="docutils literal"><span class="pre">make</span></code> in the same top-level directory of
<code class="docutils literal"><span class="pre">~/cpp-netlib-build</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ make
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>Just like with traditional GNU Make, you can add the <code class="docutils literal"><span class="pre">-j</span></code> parameter
to specify how many parallel builds to run. In case you&#8217;re in a sufficiently
powerful system and would like to parallelize the build into 4 jobs, you can
do this with:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="o">-</span><span class="n">j4</span>
</pre></div>
</div>
<p class="last">As a caveat, <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> is heavy on template metaprogramming and will
require a lot of computing and memory resources to build the individual
tests. Do this at the risk of <a class="reference external" href="http://en.wikipedia.org/wiki/Thrashing_(computer_science)">thrashing</a> your system.  However, this
compile-time burden is much reduced in recent versions.</p>
</div>
<p>Once the build has completed, you can now run the test suite by issuing:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ make test
</pre></div>
</div>
<p>You can install <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> by issuing:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>$ sudo make install
</pre></div>
</div>
<p>By default this installs <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> into <code class="docutils literal"><span class="pre">/usr/local</span></code>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>As of version 0.9.3, <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> produces three static
libraries.  Using GCC on Linux these are:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">libcppnetlib</span><span class="o">-</span><span class="n">client</span><span class="o">-</span><span class="n">connections</span><span class="o">.</span><span class="n">a</span>
<span class="n">libcppnetlib</span><span class="o">-</span><span class="n">server</span><span class="o">-</span><span class="n">parsers</span><span class="o">.</span><span class="n">a</span>
<span class="n">libcppnetlib</span><span class="o">-</span><span class="n">uri</span><span class="o">.</span><span class="n">a</span>
</pre></div>
</div>
<p class="last">Users can find them in <code class="docutils literal"><span class="pre">~/cpp-netlib-build/libs/network/src</span></code>.</p>
</div>
</div>
<div class="section" id="building-on-windows">
<h3>Building On Windows<a class="headerlink" href="#building-on-windows" title="Permalink to this headline">¶</a></h3>
<p>If you&#8217;re using the Microsoft Visual C++ compiler or the Microsoft Visual Studio
IDE and you would like to build <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> from within Visual Studio, you
can look for the solution and project files as the artifacts of the call to
<code class="docutils literal"><span class="pre">cmake</span></code> &#8211; the file should be named <code class="docutils literal"><span class="pre">CPP-NETLIB.sln</span></code> (the solution) along
with a number of project files for Visual Studio.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>As of version 0.9.3, <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code> produces three static
libraries.  Using Visual C++ on Windows they are:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="n">cppnetlib</span><span class="o">-</span><span class="n">client</span><span class="o">-</span><span class="n">connections</span><span class="o">.</span><span class="n">lib</span>
<span class="n">cppnetlib</span><span class="o">-</span><span class="n">server</span><span class="o">-</span><span class="n">parsers</span><span class="o">.</span><span class="n">lib</span>
<span class="n">cppnetlib</span><span class="o">-</span><span class="n">uri</span><span class="o">.</span><span class="n">lib</span>
</pre></div>
</div>
<p class="last">Users can find them in <code class="docutils literal"><span class="pre">~/cpp-netlib-build/libs/network/src</span></code>.</p>
</div>
</div>
</div>
<div class="section" id="using-cpp-netlib">
<h2>Using <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code><a class="headerlink" href="#using-cpp-netlib" title="Permalink to this headline">¶</a></h2>
<div class="section" id="cmake-projects">
<h3>CMake projects<a class="headerlink" href="#cmake-projects" title="Permalink to this headline">¶</a></h3>
<p>Projects using CMake can add the following lines in their <code class="docutils literal"><span class="pre">CMakeLists.txt</span></code> to
be able to use <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span>set ( CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} ~/cpp-netlib-build )
find_package ( cppnetlib 0.11.0 REQUIRED )
include_directories ( ${CPPNETLIB_INCLUDE_DIRS} )
target_link_libraries ( MyApplication ${CPPNETLIB_LIBRARIES} )
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Setting <code class="docutils literal"><span class="pre">CMAKE_PREFIX_PATH</span></code> is only required when <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code>
is not installed to a location that CMake searches.  When <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code>
is installed to the default location (<code class="docutils literal"><span class="pre">/usr/local</span></code>), <code class="docutils literal"><span class="pre">CMake</span></code> can find it.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">We assume that <code class="docutils literal"><span class="pre">MyApplication</span></code> is the application that you are
building and which depends on <code class="xref py py-mod docutils literal"><span class="pre">cpp-netlib</span></code>.</p>
</div>
</div>
</div>
<div class="section" id="reporting-issues-getting-support">
<h2>Reporting Issues, Getting Support<a class="headerlink" href="#reporting-issues-getting-support" title="Permalink to this headline">¶</a></h2>
<p>In case you find yourself stuck or if you&#8217;ve found a bug (or you want to just
join the discussion) you have a few options to choose from.</p>
<p>For reporting bugs, feature requests, and asking questions about the
implementation and/or the documentation, you can go to the GitHub issues page
for the project at <a class="reference external" href="http://github.com/cpp-netlib/cpp-netlib/issues">http://github.com/cpp-netlib/cpp-netlib/issues</a>.</p>
<p>You can also opt to join the developers mailing list for a more personal
interaction with the developers of the project. You can join the mailing list
through <a class="reference external" href="http://groups.google.com/forum/#!forum/cpp-netlib">http://groups.google.com/forum/#!forum/cpp-netlib</a>.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="contents.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Getting Started</a><ul>
<li><a class="reference internal" href="#downloading-an-official-release">Downloading an official release</a></li>
<li><a class="reference internal" href="#downloading-a-development-version">Downloading a development version</a></li>
<li><a class="reference internal" href="#getting-boost">Getting Boost</a></li>
<li><a class="reference internal" href="#getting-cmake">Getting CMake</a></li>
<li><a class="reference internal" href="#building-with-cmake">Building with CMake</a><ul>
<li><a class="reference internal" href="#building-on-linux">Building on Linux</a></li>
<li><a class="reference internal" href="#building-on-windows">Building On Windows</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-cpp-netlib">Using <code class="docutils literal"><span class="pre">cpp-netlib</span></code></a><ul>
<li><a class="reference internal" href="#cmake-projects">CMake projects</a></li>
</ul>
</li>
<li><a class="reference internal" href="#reporting-issues-getting-support">Reporting Issues, Getting Support</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="whats_new.html"
                        title="previous chapter">What&#8217;s New</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="examples.html"
                        title="next chapter">Examples</a></p>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    <p class="searchtip" style="font-size: 90%">
    Enter search terms or a module, class or function name.
    </p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="examples.html" title="Examples"
             >next</a></li>
        <li class="right" >
          <a href="whats_new.html" title="What’s New"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="contents.html">cpp-netlib v0.12.0</a> &raquo;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &copy; Copyright 2008-2014, Glyn Matthews, Dean Michael Berris; 2013 Google, Inc..
      Last updated on Mar 29, 2016.
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.3.6.
    </div>
  </body>
</html>